<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Building and Installing the Library</title>
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="Boost.Regex 7.0.1">
<link rel="up" href="../index.html" title="Boost.Regex 7.0.1">
<link rel="prev" href="configuration/tuning.html" title="Algorithm Tuning">
<link rel="next" href="intro.html" title="Introduction and Overview">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="configuration/tuning.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="intro.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="boost_regex.install"></a><a class="link" href="install.html" title="Building and Installing the Library">Building and Installing the Library</a>
</h2></div></div></div>
<p>
      When you extract the library from its zip file, you must preserve its internal
      directory structure (for example by using the -d option when extracting). If
      you didn't do that when extracting, then you'd better stop reading this, delete
      the files you just extracted, and try again!
    </p>
<p>
      This library should not need configuring before use; most popular compilers/standard
      libraries/platforms are already supported "as is". If you do experience
      configuration problems, or just want to test the configuration with your compiler,
      then the process is the same as for all of boost; see the <a href="../../../../config/index.html" target="_top">configuration
      library documentation</a>.
    </p>
<p>
      The library will encase all code inside namespace boost.
    </p>
<p>
      This is a header only library provided your compiler supports C++11 or later.
      Support for C++03 compilers is still present, but is now deprecated and may
      be removed without further notice!
    </p>
<p>
      The only people that still need to build the external libboost_regex library
      are those that are either:
    </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
          Using the library in C++03 mode, or,
        </li>
<li class="listitem">
          Using the deprecated POSIX C API's
        </li>
</ul></div>
<p>
      Further, this library may now be used in "standalone" mode without
      the rest of the Boost C++ libraries, in order to do this you must either:
    </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
          Have a C++17 compiler that supports <code class="computeroutput"><span class="identifier">__has_include</span></code>,
          in this case if <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code> is not present then the library will
          automoatically enter standalone mode. Or:
        </li>
<li class="listitem">
          Define BOOST_REGEX_STANDALONE when building.
        </li>
</ul></div>
<p>
      If you are using this library with ICU, note that since it is now header only,
      it will be up to you to link to the ICU libraries if you use <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">regex</span><span class="special">/</span><span class="identifier">icu</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code> unless you are using the supplied CMake
      script.
    </p>
<h5>
<a name="boost_regex.install.h0"></a>
      <span class="phrase"><a name="boost_regex.install.usage_with_cmake"></a></span><a class="link" href="install.html#boost_regex.install.usage_with_cmake">Usage
      with CMake</a>
    </h5>
<p>
      The library comes with a very basic CMakeLists.txt that allows this library
      to be used from other CMake scripts.
    </p>
<p>
      CMakeLists.txt defines two targets:
    </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
          <code class="computeroutput"><span class="identifier">Boost</span><span class="special">::</span><span class="identifier">regex</span></code> This is the target to use for normal
          header only builds.
        </li>
<li class="listitem">
          <code class="computeroutput"><span class="identifier">Boost</span><span class="special">::</span><span class="identifier">regex_icu</span></code> This is the target to use if
          you are using <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">regex</span><span class="special">/</span><span class="identifier">icu</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code> in your code, and wish to have the
          ICU dependencies taken care of for you.
        </li>
</ul></div>
<p>
      There is also one configuration option:
    </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
          BOOST_REGEX_STANDALONE when set then no other Boost libraries are targeted
          as dependencies, and Boost.Regex is placed in standalone mode. Invoke CMake
          with -DBOOST_REGEX_STANDALONE=on to enable standalone mode.
        </li></ul></div>
<h5>
<a name="boost_regex.install.h1"></a>
      <span class="phrase"><a name="boost_regex.install.c_03_users_only_deprecated_build"></a></span><a class="link" href="install.html#boost_regex.install.c_03_users_only_deprecated_build"><span class="bold"><strong>C++03 users only (DEPRECATED)</strong></span> Building with bjam</a>
    </h5>
<p>
      This is now the preferred method for building and installing legacy versions
      this library, please refer to the <a href="../../../../../more/getting_started.html" target="_top">getting
      started guide</a> for more information.
    </p>
<h5>
<a name="boost_regex.install.h2"></a>
      <span class="phrase"><a name="boost_regex.install.building_with_unicode_and_icu_su"></a></span><a class="link" href="install.html#boost_regex.install.building_with_unicode_and_icu_su">Building
      With Unicode and ICU Support</a>
    </h5>
<p>
      Boost.Regex is now capable of performing a configuration check to test whether
      ICU is already installed in your compiler's search paths. When you build you
      should see a message like this:
    </p>
<pre class="programlisting"><span class="identifier">Performing</span> <span class="identifier">configuration</span> <span class="identifier">checks</span>

    <span class="special">-</span> <span class="identifier">has_icu</span> <span class="identifier">builds</span>           <span class="special">:</span> <span class="identifier">yes</span>
</pre>
<p>
      Which means that ICU has been found, and support for it will be enabled in
      the library build.
    </p>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../doc/src/images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top"><p>
        If you don't want the regex library to use ICU then build with the "--disable-icu"
        command line option.
      </p></td></tr>
</table></div>
<p>
      If instead you see:
    </p>
<pre class="programlisting"><span class="identifier">Performing</span> <span class="identifier">configuration</span> <span class="identifier">checks</span>

    <span class="special">-</span> <span class="identifier">has_icu</span> <span class="identifier">builds</span>           <span class="special">:</span> <span class="identifier">no</span>
</pre>
<p>
      Then ICU was not found and support for it will not be compiled into the library.
      If you think that it should have been found, then you will need to take a look
      at the contents of the file <span class="emphasis"><em>boost-root/bin.v2/config.log</em></span>
      for the actual error messages obtained when the build carried out the configuration
      check. You will then need to fix these errors by ensuring your compiler gets
      invoked with the correct options. The main options that you're likely to pass
      to <code class="computeroutput"><span class="identifier">b2</span></code> are:
    </p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
              <p>
                Option
              </p>
            </th>
<th>
              <p>
                Description
              </p>
            </th>
</tr></thead>
<tbody>
<tr>
<td>
              <p>
                include=/some/path
              </p>
            </td>
<td>
              <p>
                Adds "/some/path" to the list of paths seached for include
                files, normally equivalent to <code class="computeroutput"><span class="special">-</span><span class="identifier">I</span><span class="special">/</span><span class="identifier">some</span><span class="special">/</span><span class="identifier">path</span></code> on most compilers.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                library-path=/some/path
              </p>
            </td>
<td>
              <p>
                Adds "/some/path" to the list of paths searched for external
                libraries, set this to the location of the ICU binaries if they're
                in a non-standard location.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                -sICU_ICUUC_NAME=NAME
              </p>
            </td>
<td>
              <p>
                If <code class="computeroutput"><span class="identifier">libicuuc</span></code> has a
                non-standard name then this sets the name of the library linked against,
                defaults to either <code class="computeroutput"><span class="identifier">icuuc</span></code>,
                <code class="computeroutput"><span class="identifier">icuucd</span></code>, <code class="computeroutput"><span class="identifier">sicuuc</span></code> or <code class="computeroutput"><span class="identifier">sicuucd</span></code>
                depending on build options.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                -sICU_ICUDT_NAME=NAME
              </p>
            </td>
<td>
              <p>
                If <code class="computeroutput"><span class="identifier">libicudata</span></code> has
                a non-standard name then this sets the name of the library linked
                against, defaults to either <code class="computeroutput"><span class="identifier">icudt</span></code>,
                <code class="computeroutput"><span class="identifier">icudata</span></code>, <code class="computeroutput"><span class="identifier">sicudt</span></code> or <code class="computeroutput"><span class="identifier">sicudata</span></code>
                depending on build options and platform.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                -sICU_ICUIN_NAME=NAME
              </p>
            </td>
<td>
              <p>
                If <code class="computeroutput"><span class="identifier">libicui18n</span></code> has
                a non-standatd name then this sets the name of the library linked
                against, defaults to either <code class="computeroutput"><span class="identifier">icui18n</span></code>,
                <code class="computeroutput"><span class="identifier">icuin</span></code>, <code class="computeroutput"><span class="identifier">icuind</span></code>, sicuin<code class="computeroutput"> <span class="keyword">or</span>
                </code>sicuins` depending on build options and platform.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                cxxstd=XX
              </p>
            </td>
<td>
              <p>
                Sets the C++ standard supported: XX should be either 03, 11, 14,
                17 or 2a.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                cxxflags="FLAGS"
              </p>
            </td>
<td>
              <p>
                Passes "FLAGS" directly to the compiler, an option of last
                resort!
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                linflags="FLAGS"
              </p>
            </td>
<td>
              <p>
                Passes "FLAGS" directly to the compiler on the link step,
                an option of last resort!
              </p>
            </td>
</tr>
</tbody>
</table></div>
<div class="important"><table border="0" summary="Important">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td>
<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top"><p>
        Configuration results are cached - if you try rebuilding with different compiler
        options then add an "-a" to the bjam command line to force all
        targets to be rebuilt.
      </p></td></tr>
</table></div>
<div class="important"><table border="0" summary="Important">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td>
<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top"><p>
        ICU is a C++ library just like Boost is, as such your copy of ICU must have
        been built with the same C++ compiler (and compiler version) that you are
        using to build Boost. Boost.Regex will not work correctly unless you ensure
        that this is the case: it is up to you to ensure that the version of ICU
        you are using is binary compatible with the toolset you use to build Boost.
      </p></td></tr>
</table></div>
<p>
      And finally, if you want to build/test with multiple compiler versions, all
      with different ICU builds, then the only way to achieve that currently is to
      modify your user-config.jam so that each toolset has the necessary compiler/linker
      options set so that ICU is found automatically by the configuration step (providing
      the ICU binaries use the standard names, all you have to add is the appropriate
      header-include and linker-search paths).
    </p>
<h5>
<a name="boost_regex.install.h3"></a>
      <span class="phrase"><a name="boost_regex.install.building_from_source"></a></span><a class="link" href="install.html#boost_regex.install.building_from_source">Building
      from Source</a>
    </h5>
<p>
      The Regex library is "just a bunch of source files": nothing special
      is required to build them.
    </p>
<p>
      You can either build the files under boost-path/libs/regex/src/*.cpp as a library,
      or add them directly to your project. This is particularly useful if you need
      to use specific compiler options not supported by the default Boost build.
    </p>
<p>
      There are two #defines you should be aware of:
    </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
          BOOST_HAS_ICU should be defined if you want ICU support compiled in.
        </li>
<li class="listitem">
          BOOST_REGEX_DYN_LINK should be defined if you are building a DLL on Windows.
        </li>
</ul></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 1998-2013 John Maddock<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="configuration/tuning.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="intro.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
